home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2000 #4 / Amiga Plus CD - 2000 - No. 4.iso / Tools / Dev / Bgui / AutoDoc / bgui.doc < prev    next >
Encoding:
Text File  |  2000-05-09  |  35.1 KB  |  1,327 lines
  1. TABLE OF CONTENTS
  2.  
  3. bgui.library/BGUI_AllocBitMap
  4. bgui.library/BGUI_CreateRPortBitMap
  5. bgui.library/BGUI_DoGadgetMethodA
  6. bgui.library/BGUI_FillRectPattern
  7. bgui.library/BGUI_FreeBitMap
  8. bgui.library/BGUI_FreeClass
  9. bgui.library/BGUI_FreeRPortBitMap
  10. bgui.library/BGUI_GetCatalogStr
  11. bgui.library/BGUI_GetClassPtr
  12. bgui.library/BGUI_GetLocaleStr
  13. bgui.library/BGUI_Help
  14. bgui.library/BGUI_InfoText
  15. bgui.library/BGUI_InfoTextSize
  16. bgui.library/BGUI_LockWindow
  17. bgui.library/BGUI_MakeClassA
  18. bgui.library/BGUI_NewObjectA
  19. bgui.library/BGUI_PackStructureTags
  20. bgui.library/BGUI_PostRender
  21. bgui.library/BGUI_RequestA
  22. bgui.library/BGUI_UnlockWindow
  23. bgui.library/BGUI_UnpackStructureTags
  24.  
  25. bgui.library/BGUI_AllocBitMap
  26.  
  27. NAME
  28.    BGUI_AllocBitMap -- Allocate a BitMap.
  29.  
  30.    ** V40.4 **
  31.  
  32. SYNOPSIS
  33.  
  34.    bitmap = BGUI_AllocBitMap( width, height, depth, flags, friend )
  35.    D0                         D0     D1      D2     D3     A0
  36.  
  37.    struct BitMap *BGUI_AllocBitMap( ULONG, ULONG, ULONG, ULONG,
  38.                                     struct BitMap * )
  39.  
  40. FUNCTION
  41.  
  42.    Allocates and initializes a BitMap structure and its bitplanes. Under
  43.    OS 3.0 or later it reverts to the graphics.library/AllocBitMap()
  44.    routine. On earlier versions of the OS it will allocate and initialize
  45.    the BitMap structure and bitplanes itself.
  46.  
  47. INPUTS
  48.  
  49.    width    -  The width in pixels of the desired BitMap.
  50.  
  51.    height   -  The height in pixels of the desired BitMap.
  52.  
  53.    depth    -  The number of bitplanes of the desired BitMap.
  54.  
  55.    flags    -  BMF_CLEAR to specify that the allocated raster should be
  56.                filled with color 0.
  57.  
  58.                BMF_DISPLAYABLE to specify that this bitmap data should
  59.                be allocated in such a manner that it can be displayed.
  60.                Displayable data has more severe alignment restrictions
  61.                than non-displayable data in some systems.
  62.  
  63.                BMF_INTERLEAVED tells graphics that you would like your
  64.                bitmap to be allocated with one large chunk of display
  65.                memory for all bitplanes. This minimizes color flashing
  66.                on deep displays. If there is not enough contiguous RAM
  67.                for an interleaved bitmap, graphics.library will fall
  68.                back to a non-interleaved one.
  69.  
  70.                BMF_MINPLANES causes graphics to only allocate enough space
  71.                in the bitmap structure for "depth" plane pointers. This
  72.                is for system use and should not be used by applications use
  73.                as it is inefficient, and may waste memory.
  74.  
  75.    friend   -  See graphics.library/AllocBitMap().
  76.  
  77. RESULT
  78.  
  79.    A pointer to the allocated and initialized BitMap structure or NULL
  80.    in case of a failure.
  81.  
  82. NOTES
  83.  
  84.    Under OS 2.04 the "friend" parameter has no meaning. The only flag
  85.    available under OS 2.04 is the BMF_CLEAR flag which will clear the
  86.    bitplane data.
  87.  
  88. BUGS
  89.    None known.
  90.  
  91. SEE ALSO
  92.    bgui.library/BGUI_FreeBitMap(), graphics.library/AllocBitMap()
  93.  
  94. bgui.library/BGUI_CreateRPortBitMap
  95.  
  96. NAME
  97.  
  98.    BGUI_CreateRPortBitMap -- Create a RastPort and BitMap at the same time.
  99.  
  100.    ** V40.4 **
  101.  
  102. SYNOPSIS
  103.  
  104.    rport = BGUI_CreateRPortBitMap( src, width, height, depth )
  105.    D0                              A0   D0     D1      D2
  106.  
  107.    struct RastPort *BGUI_CreateRPortBitMap( struct RastPort *, ULONG,
  108.                                             ULONG, ULONG )
  109.  
  110. FUNCTION
  111.  
  112.    To  allocate  and  initialize  a RastPort and BitMap. The routine will
  113.    setup the RastPort attributes according to the source RastPort when
  114.    available. If no source RastPort is made available the resulting
  115.    RastPort is initialized by graphics.library/InitRastPort().
  116.  
  117. INPUTS
  118.  
  119.    src      -  A pointer to the source RastPort from which the attributes
  120.                for the created RastPort are copied. When this is not
  121.                specified, the created RastPort is initialized with the
  122.                graphics.library/InitRastPort() routine.
  123.  
  124.    width    -  The width in pixels of the BitMap attached to the RastPort.
  125.  
  126.    height   -  The height in pixels of the BitMap attached to the RastPort.
  127.  
  128.    depth    -  The number of bitplanes of the BitMap attached to the
  129.                RastPort.
  130.  
  131. RESULT
  132.  
  133.    A pointer to the created RastPort structure or NULL uppon failure.
  134.  
  135. NOTES
  136.  
  137.    The created RastPort does not have a layer attached to it, so clipping
  138.    is not possible. You are responsible to ensure that any rendering which
  139.    occurs in the RastPort remains inside the RastPort bounds.
  140.  
  141. BUGS
  142.  
  143.    None known.
  144.  
  145. SEE ALSO
  146.  
  147.    bgui.library/BGUI_FreeRPortBitMap()
  148.  
  149. bgui.library/BGUI_DoGadgetMethodA
  150.  
  151. NAME
  152.  
  153.    BGUI_DoGadgetMethodA -- Invoke a method on a BOOPSI gadget.
  154.    BGUI_DoGadgetMethod -- Varargs version.
  155.  
  156. SYNOPSIS
  157.  
  158.    result = BGUI_DoGadgetMethodA( gad, win, req, msg )
  159.    D0                             A0   A1   A2   A3
  160.  
  161.    ULONG BGUI_DoGadgetMethodA( Object *, struct Window *,
  162.                                struct Requester *, Msg )
  163.  
  164.    ULONG BGUI_DoGadgetMethod( Object *, struct Window *,
  165.                               struct Requester *, ULONG, ... )
  166.  
  167. FUNCTION
  168.  
  169.    To invoke a method on a BOOPSI gadget in a way similar to the DoMethod()
  170.    function in amiga.lib, with the advantage that context information for
  171.    the gadget is included in the method by means of a GadgetInfo
  172.    structure.
  173.  
  174. INPUTS
  175.  
  176.    gad   -  A pointer to the BOOPSI gadget on which the method is
  177.             invoked.
  178.  
  179.    win   -  A pointer to the window on which the BOOPSI gadget is
  180.             located.
  181.  
  182.    req   -  Normally a pointer to the requester on which the BOOPSI
  183.             gadget is located. Since BGUI does not support objects
  184.             on requesters you should put NULL here.
  185.  
  186.    msg   -  A pointer to the message to send to the BOOPSI gadget.
  187.  
  188. RESULT
  189.  
  190.    The object does whatever it needs to do which may include updating
  191.    it's visuals. The return value is defined per each method.
  192.  
  193. NOTES
  194.  
  195.    This function invokes the specified method with a GadgetInfo derived
  196.    from the 'win' and 'req' pointers. The GadgetInfo is passed as the
  197.    second parameter of the message, except for OM_NEW, OM_SET, OM_NOTIFY,
  198.    and OM_UPDATE, where the GadgetInfo is passed as the third parameter.
  199.  
  200.    Custom gadget implemetors should take note of this.  Always put the
  201.    GadgetInfo in the second parameter of the message.
  202.  
  203. SEE ALSO
  204.  
  205.    intuition.library/DoGadgetMethod(), intuition.library/SetGadgetAttrs()
  206.  
  207. bgui.library/BGUI_FillRectPattern
  208.  
  209. NAME
  210.  
  211.    BGUI_FillRectPattern -- Fill a rectangle with a pattern
  212.  
  213.    ** V41.3 **
  214.  
  215. SYNOPSIS
  216.  
  217.    BGUI_FillRectPattern( rport, pat, X1, Y1, X2, Y2)
  218.                          A1     A0   D0  D1  D2  D3
  219.  
  220.    void BGUI_FillRectPattern( struct RastPort *, struct bguiPattern *,
  221.                               ULONG, ULONG, ULONG, ULONG)
  222.  
  223. FUNCTION
  224.  
  225.    This function fills a given RastPort with the given bguiPattern within
  226.    the constraints provided.
  227.  
  228.    This function is similar to graphics.library/BlitBitMapRastPort() but
  229.    allows for additional convenience and flexibility.
  230.  
  231. INPUTS
  232.  
  233.    rport    -  A pointer to the RastPort that you wish to copy the pattern to.
  234.  
  235.    pat      -  A bguiPattern structure that you must initialize before use:
  236.  
  237.                ULONG bp_Flags
  238.  
  239.                   0, or one of the following flags:
  240.  
  241.                   BPF_RELATIVE_ORIGIN
  242.                      Origin is relative to the box constraints given below.
  243.  
  244.                UWORD bp_Left, UWORD bp_Top
  245.  
  246.                   Offset into the bitmap which follows.
  247.  
  248.                UWORD bp_Width, UWORD bp_Height
  249.  
  250.                   Defines the size of the 'cut' taken from the bitmap.
  251.  
  252.                struct BitMap *bp_BitMap
  253.  
  254.                   Pointer to the BitMap structure you wish to use in the
  255.                   fill. Naturally, it must be initialized and valid.
  256.  
  257.                Object *bp_Object
  258.  
  259.                   Not currently used.
  260.  
  261.    ULONG X1 -
  262.    ULONG Y1 -  The upper-left corner of the RastPort you are filling.
  263.  
  264.    ULONG X2 -
  265.    ULONG Y2 -  The lower-right corner of the RastPort you are filling.
  266.  
  267.  
  268. RESULT
  269.  
  270.    No return value. If successful, the RastPort will be filled with
  271.    the desired portion of the desired pattern.
  272.  
  273. NOTES
  274.  
  275.  
  276. BUGS
  277.  
  278.    None known.
  279.  
  280. SEE ALSO
  281.  
  282.    libraries/bgui.h, graphics.library/BltBitMapRastPort()
  283.  
  284.  
  285.  
  286. bgui.library/BGUI_FreeBitMap
  287.  
  288. NAME
  289.  
  290.    BGUI_FreeBitMap -- Free a BitMap created with BGUI_AllocBitMap().
  291.  
  292.    ** V40.4 **
  293.  
  294. SYNOPSIS
  295.  
  296.    BGUI_FreeBitMap( bitmap )
  297.                     A0
  298.  
  299.    VOID BGUI_FreeBitMap( struct BitMap * )
  300.  
  301. FUNCTION
  302.  
  303.    To deallocate a BitMap structure and bitplane data previously created
  304.    with BGUI_AllocBitMap().  Before the bitmap is actually freed a call
  305.    to WaitBlit() is made to make sure it is safe.
  306.  
  307. INPUTS
  308.  
  309.    bitmap   - A pointer to the BitMap structure.
  310.  
  311. BUGS
  312.  
  313.    None known.
  314.  
  315. SEE ALSO
  316.  
  317.    bgui.library/BGUI_AllocBitMap(), graphics.library/WaitBlit()
  318.  
  319. bgui.library/BGUI_FreeClass
  320.  
  321. NAME
  322.  
  323.    BGUI_FreeClass -- Free a class created with BGUI_MakeClassA().
  324.  
  325.    ** V41.7 **
  326.  
  327. SYNOPSIS
  328.  
  329.    success = BGUI_FreeClass ( class )
  330.    D0                         A0
  331.  
  332.    BOOL BGUI_FreeClass ( Class * )
  333.  
  334. FUNCTION
  335.  
  336.    Free memory and resources for a class that was created with
  337.    BGUI_MakeClassA().  The class OM_DISPOSE method will be called before
  338.    disposing the class as discussed in the description of the
  339.    CLASS_ClassDispatcher parameter of BGUI_MakeClassA() function.
  340.  
  341. INPUTS
  342.  
  343.    class -  The class you wish to free up.
  344.  
  345. RESULT
  346.  
  347.    TRUE if success, FALSE if not.
  348.  
  349. NOTES
  350.  
  351.  
  352. BUGS
  353.  
  354.    None known.
  355.  
  356. SEE ALSO
  357.  
  358.    libraries/bgui.h, bgui.library/BGUI_MakeClassA()
  359.  
  360.  
  361.  
  362. bgui.library/BGUI_FreeRPortBitMap
  363.  
  364. NAME
  365.  
  366.    BGUI_FreeRPortBitMap -- Free a RastPort created by BGUI_CreateRPortBitMap()
  367.  
  368.    ** V40.4 **
  369.  
  370. SYNOPSIS
  371.  
  372.    BGUI_FreeRPortBitMap( rport )
  373.                          A0
  374.  
  375.    VOID BGUI_FreeRPortBitMap( struct RastPort * )
  376.  
  377. FUNCTION
  378.  
  379.    To free the RastPort and BitMap created by an earlier call to the
  380.    BGUI_CreateRPortBitMap() function.
  381.  
  382. INPUTS
  383.  
  384.    rport - A pointer to the RastPort structure to free.
  385.  
  386. BUGS
  387.    None known.
  388.  
  389. SEE ALSO
  390.    bgui.library/BGUI_CreateRPortBitMap()
  391.  
  392. bgui.library/BGUI_GetCatalogStr
  393.  
  394. NAME
  395.  
  396.    BGUI_GetCatalogStr -- Obtain a pointer to a localized string from a
  397.                          message catalog.
  398.  
  399.    ** V41.3 **
  400.  
  401. SYNOPSIS
  402.  
  403.    String = BGUI_GetCatalogStr( bgui_loc, ID, default )
  404.    D0                           A0        D0  A1
  405.  
  406.    STRPTR *BGUI_GetCatalogStr( struct bguiLocale *, ULONG, STRPTR );
  407.  
  408. FUNCTION
  409.  
  410.    This function fetches a locale string from a specific localization
  411.    catalog. If the localized string indicated by ID is not found, the
  412.    default string is returned.
  413.  
  414.    This function is similar to locale.library/GetCatalogStr() but allows
  415.    for additional flexibility via hooks.
  416.  
  417. INPUTS
  418.  
  419.    bgui_loc -  A pointer to a bguiLocale structure that you have filled out:
  420.  
  421.                struct Locale *bl_Locale
  422.  
  423.                   Not used by this function.
  424.  
  425.                struct Catalog *bl_Catalog
  426.  
  427.                   A Catalog structure you initialize using the locale.library
  428.                   function OpenCatalog(). If it is NULL, the default string
  429.                   is returned.
  430.  
  431.                struct Hook *blLocaleStrHook
  432.  
  433.                   Not used by this function.
  434.  
  435.                struct Hook *blCatalogStrHook
  436.  
  437.                   If this is filled in, the function indicated is called to
  438.                   retrieve the string pointer. It is passed a bguiCatalogStr
  439.                   struct that contains the ID of the desired string and the
  440.                   default string itself.
  441.  
  442.                   If this is not filled in, locale.library/GetCatalogStr() is
  443.                   called.
  444.  
  445.     ID      -  The number of the locale string you wish to retrieve.
  446.  
  447.     default -  The default string to return if the localized version is not
  448.                found.
  449.  
  450. RESULT
  451.  
  452.    A pointer to the desired string.  This string is READ ONLY and cannot be
  453.    changed by your program! This string is valid only as long as the catalog
  454.    remains open.
  455.  
  456.    If the ID is out of bounds, the default string will be returned.
  457.  
  458. NOTES
  459.  
  460.    locale.library must be opened before using this function. If it is not,
  461.    a NULL pointer will always be returned unless you use your own hook.
  462.  
  463.    The catalog must be closed by you -- BGUI does not clean it up.
  464.  
  465. BUGS
  466.  
  467.    None known.
  468.  
  469. SEE ALSO
  470.  
  471.    libraries/bgui.h, locale.library/OpenCatalog(),
  472.    locale.library/GetCatalogStr()
  473.  
  474.  
  475.  
  476. bgui.library/BGUI_GetClassPtr
  477.  
  478. NAME
  479.  
  480.    BGUI_GetClassPtr -- Obtain a pointer to a BGUI class.
  481.  
  482. SYNOPSIS
  483.  
  484.    class = BGUI_GetClassPtr( classID )
  485.    D0                        D0
  486.  
  487.    Class *BGUI_GetClassPtr( ULONG );
  488.  
  489. FUNCTION
  490.  
  491.    This function is meant to provide class writers an easy way to obtain a
  492.    pointer to one of the bgui.library classes. The pointer returned by this
  493.    routine may _only_ be used to subclass or to obtain objects from. Reading
  494.    from or writing to the class structure is NOT allowed.
  495.  
  496. INPUTS
  497.  
  498.    classID  - The numeric ID of the class you need.
  499.  
  500. RESULT
  501.  
  502.    A pointer to the requested class or NULL if the call was  unsuccessfull.
  503.  
  504. BUGS
  505.  
  506.    None known.
  507.  
  508. SEE ALSO
  509.  
  510.    libraries/bgui.h
  511.  
  512. bgui.library/BGUI_GetLocaleStr
  513.  
  514. NAME
  515.  
  516.    BGUI_GetLocaleStr -- Obtain a pointer to a localized string.
  517.  
  518.    ** V41.3 **
  519.  
  520. SYNOPSIS
  521.  
  522.    String = BGUI_GetLocaleStr( locale, ID )
  523.    D0                          A0      D0
  524.  
  525.    STRPTR *BGUI_GetLocaleStr( struct bguiLocale *, ULONG );
  526.  
  527. FUNCTION
  528.  
  529.    This function fetches a localized string for the given locale.
  530.  
  531.    This function is similar to locale.library/GetLocaleStr() but allows
  532.    for additional flexibility via hooks.
  533.  
  534. INPUTS
  535.  
  536.    bgui_loc -  A pointer to a bguiLocale structure that you have filled out:
  537.  
  538.                struct Locale *bl_Locale
  539.  
  540.                   A Locale structure you initialize using the locale.library
  541.                   function OpenLocale().
  542.  
  543.                struct Catalog *bl_Catalog
  544.  
  545.                   Not used by this function.
  546.  
  547.                struct Hook *blLocaleStrHook
  548.  
  549.                   If this is filled in, the function indicated is called to
  550.                   retrieve the string pointer. It is passed a bguiLocaleStr
  551.                   struct that contains the ID of the locale string.
  552.  
  553.                   If this is not filled in, locale.library/GetLocaleStr() is
  554.                   called.
  555.  
  556.                struct Hook *blCatalogStrHook
  557.  
  558.                   Not used by this function.
  559.  
  560.     ID      -  The number of the locale string you wish to retrieve.
  561.  
  562. RESULT
  563.  
  564.    A pointer to the desired locale string.  This string is READ ONLY and
  565.    cannot be changed by your program! This string will remain valid until
  566.    you close the locale.
  567.  
  568.    If the ID is out of bounds, a NULL pointer will be returned.
  569.  
  570. NOTES
  571.  
  572.    locale.library must be opened before using this function. If it is not,
  573.    a NULL pointer will always be returned unless you use your own hook.
  574.  
  575.    You are responsible for closing the locale once it is opened.
  576.  
  577. BUGS
  578.  
  579.    None known.
  580.  
  581. SEE ALSO
  582.  
  583.    libraries/bgui.h, locale.library/OpenLocale(),
  584.    locale.library/GetLocaleStr()
  585.  
  586.  
  587. bgui.library/BGUI_Help
  588.  
  589. NAME
  590.  
  591.    BGUI_Help -- Put up a simple synchronus AmigaGuide help file.
  592.  
  593. SYNOPSIS
  594.  
  595.    success = BGUI_Help( win, file, node, line )
  596.    D0                   A0   A1    A2    D0
  597.  
  598.    BOOL BGUI_Help( struct Window *, UBYTE *, UBYTE *, ULONG )
  599.  
  600. FUNCTION
  601.  
  602.    To show additional online-help using the AmigaGuide system.
  603.  
  604. INPUTS
  605.  
  606.    win   -  A pointer to the window from which the AmigaGuide help
  607.             session is being invoked.
  608.  
  609.    name  -  A pointer to the full path name of the amigaguide file.
  610.  
  611.    node  -  A pointer to the node name to display.
  612.  
  613.    line  -  The line number to display.
  614.  
  615. RESULT
  616.  
  617.    TRUE uppon success and FALSE if something went wrong.
  618.  
  619. BUGS
  620.  
  621.    None known.
  622.  
  623. SEE ALSO
  624.  
  625.    amigaguide.library/OpenAmigaGuideA()
  626.  
  627. bgui.library/BGUI_InfoText
  628.  
  629. NAME
  630.  
  631.    BGUI_InfoText -- Render text using BGUI infoclass command sequences.
  632.  
  633.    ** V40.8 **
  634.  
  635. SYNOPSIS
  636.  
  637.    BGUI_InfoText( rp, text, bounds, drawinfo )
  638.                   A0  A1    A2      A3
  639.  
  640.    void BGUI_InfoText( struct RastPort *, UBYTE *, struct IBox *,
  641.                        struct DraInfo * )
  642.  
  643. FUNCTION
  644.  
  645.    To render text with infoclass command sequences inside the given
  646.    bounds. The rendering routine will automatically truncate all text
  647.    that will not fit inside the given bounds.
  648.  
  649.    Also the text, when possible, is centered vertically in the given
  650.    bounds.
  651.  
  652. INPUTS
  653.  
  654.    rp       -  A pointer to the RastPort in which the text is to be rendered.
  655.  
  656.    text     -  A pointer to the text to render. All infoclass command
  657.                sequences are supported.  They are:
  658.  
  659.                \33b     -  Bold text.
  660.                \33i     -  Italics text.
  661.                \33u     -  Underlined text.
  662.                \33n     -  Normal text.
  663.                \33c     -  Center this and the following text lines.
  664.                \33l     -  Left-justify this and the following text lines.
  665.                \33r     -  Right-justify this and the following text lines.
  666.                \33d<n>  -  Set drawinfo pen <n>.
  667.                \33p<n>  -  Set pen <n>.
  668.                \n       -  Start a new line of text.
  669.  
  670.                Please note that the \33c, \33l and \33r command sequences
  671.                can only be used at the beginning of a new line.
  672.  
  673.    bounds   -  A pointer to a struct IBox in which the bounds of the area
  674.                in which is rendered are described.
  675.  
  676.    drawinfo -  A pointer to the screen's DrawInfo structure. This is
  677.                used to find pen information for the screen. When this is
  678.                NULL a default set of pens is used.
  679.  
  680. RESULT
  681.  
  682.    None.
  683.  
  684. BUGS
  685.  
  686.    None known.
  687.  
  688. SEE ALSO
  689.  
  690.    bgui.library/BGUI_InfoTextSize
  691.  
  692. bgui.library/BGUI_InfoTextSize
  693.  
  694. NAME
  695.  
  696.    BGUI_InfoTextSize -- Get pixel size of text with command sequences.
  697.  
  698.    ** V40.8 **
  699.  
  700. SYNOPSIS
  701.  
  702.    BGUI_InfoTextSize( rp, text, width, height )
  703.                       A0  A1    A2     A3
  704.  
  705.    void BGUI_InfoTextSize( struct RastPort *, UBYTE *, UWORD *, UWORD * )
  706.  
  707. FUNCTION
  708.  
  709.    To compute the complete width and height of a text with BGUI infoclass
  710.    command sequences. Result is in pixels.
  711.  
  712. INPUTS
  713.  
  714.    rp       -  The RastPort which is used to base the computations on.
  715.  
  716.    text     -  A pointer to the text.
  717.  
  718.    width    -  A pointer to storage space to hold the pixel width of the
  719.                text. May be NULL in which case the width is not computed.
  720.  
  721.    height   -  A pointer to storage space to hold the pixel height of the
  722.                text. May be NULL in which case the height is not computed.
  723.  
  724. RESULT
  725.  
  726.    None
  727.  
  728. BUGS
  729.  
  730.    None known.
  731.  
  732. SEE ALSO
  733.  
  734.    bgui.library/BGUI_InfoText
  735.  
  736. bgui.library/BGUI_LockWindow
  737.  
  738. NAME
  739.  
  740.    BGUI_LockWindow -- Disable a window from receiving IDCMP mesages.
  741.  
  742. SYNOPSIS
  743.  
  744.    lock = BGUI_LockWindow( win )
  745.    D0                      A0
  746.  
  747.    APTR BGUI_LockWindow( struct Window * )
  748.  
  749. FUNCTION
  750.  
  751.    To disable a window from receiving IDCMP messages at its message port.
  752.    This is done by putting up an invisible requester and a busy pointer
  753.    (same as the workbench uses). The only thing possible with locked windows
  754.    is moving it with the dragbar and depth gadget.
  755.  
  756. INPUTS
  757.  
  758.    win   -  A pointer to the window to lock.
  759.  
  760. RESULT
  761.  
  762.    Lock will point to some private data if successfull or NULL if not.
  763.  
  764. BUGS
  765.  
  766.    None known.
  767.  
  768. SEE ALSO
  769.  
  770.    bgui.library/BGUI_UnlockWindow()
  771.  
  772. bgui.library/BGUI_MakeClassA
  773.  
  774. vNAME
  775.  
  776.    BGUI_MakeClassA -- Set up a new class.
  777.    BGUI_MakeClass  -- VarArgs version
  778.  
  779.    ** V41.7 **
  780.  
  781. SYNOPSIS
  782.  
  783.    BGUI_MakeClass ( tag1, ...)
  784.                     A0
  785.  
  786.    BGUI_MakeClassA( tagitem )
  787.                     A0
  788.  
  789.    Class *BGUI_MakeClass ( ULONG, ...)
  790.  
  791.    Class *BGUI_MakeClassA( struct TagItem *)
  792.  
  793. FUNCTION
  794.  
  795.    For class implementors only.
  796.  
  797.    This function creates a new BGUI class. The superclass should be defined
  798.    to be another BGUI class; all classes are decendants of the 'rootclass.'
  799.  
  800. INPUTS
  801.  
  802.    The following tags are supported:
  803.  
  804.       CLASS_SuperClassBGUI
  805.          (ULONG) The class ID of the class' superclass IF the class is a
  806.          subclass of one of the known BGUI classes.
  807.  
  808.       CLASS_SuperClass
  809.          (ULONG) If CLASS_SuperClassBGUI is missing, this must be set to
  810.          a pointer to an already created class (superclass).
  811.  
  812.      CLASS_SuperClassID
  813.          (STRPTR ) If CLASS_SuperClassBGUI is missing and if
  814.          CLASS_SuperClass is missing or it is NULL, this may be set to the
  815.          name (character string) of any existing superclass of the class to
  816.          be created.  The default value is "rootclass".  This is the same
  817.          as required for intuition.library/MakeClass() and will be passed
  818.          to it.
  819.  
  820.      CLASS_ClassID
  821.          (STRPTR) The name (character string) of the class. Only required
  822.          if this class is to created is to be made public.  This is the
  823.          same as required for intuition.library/MakeClass() and will be
  824.          passed to it.
  825.  
  826.       CLASS_ClassSize
  827.          (ULONG) The size in bytes of the class private data space.  That
  828.          memory space will be allocated and pointed to by the class
  829.          cl_UserData field.  Class implementors should take advantage of
  830.          this data space to store class specific global data.
  831.  
  832.       CLASS_ObjectSize
  833.          (ULONG) The size in bytes of the instance data of each object of
  834.          the class.
  835.  
  836.       CLASS_Flags
  837.          (ULONG) Flags; these are the same as required for
  838.          intuition.library/MakeClass() and will be passed to it. Defaults
  839.          to 0.
  840.  
  841.       CLASS_Dispatcher
  842.          (HOOKFUNC) Pointer to the dispatcher function for objects of this
  843.          class. This is NOT a callback hook, but a function pointer. The
  844.          function pointed to must accept data as follows:
  845.  
  846.             REG(A0) Class *cl, REG(A2) Object *obj, REG(A1) Msg msg
  847.  
  848.          If this tag is not specified, the default jump table defined
  849.          in CLASS_DFTAble is used.
  850.  
  851.       CLASS_DFTable
  852.          (DPFUNC *) Pointer to the dispatcher's function lookup table.
  853.          This table lists all methods that the class can perform and
  854.          a pointer to that method.
  855.  
  856.       CLASS_ClassDispatcher
  857.          (HOOKFUNC) Pointer to the dispatcher for this class (same format
  858.          as CLASS_Dispatcher).  This dispatcher is used to call class
  859.          specific methods.  This is an extension to intuition BOOPSI
  860.          classes.  Besides the object methods, the classes may have their
  861.          own methods.
  862.  
  863.          Currently, only OM_NEW and OM_DISPOSE are supported by BGUI.
  864.          OM_NEW is called after a class is successfuly created right
  865.          before it returns from BGUI_MakeClass.  BGUI will pass to OM_NEW
  866.          the pointer of the class just created and NULL as object instance
  867.          pointer.
  868.  
  869.          Class implementors should use this method to initialize the
  870.          private class data structure (given by the cl_UserData field) and
  871.          allocate any resources needed globally by the class' objects, like
  872.          for instance external library pointers.  If the initialization
  873.          succeeds the method should return TRUE.  Otherwise, BGUI_MakeClass
  874.          will fail disposing the class that was created before calling
  875.          OM_NEW.
  876.  
  877.          OM_DISPOSE is called by BGUI_FreeClass.  Class implementors should
  878.          use it dispose any resources allocated during the class life time.
  879.          If it fails the method should return FALSE, the class is not freed
  880.          and BGUI_FreeClass fails.
  881.  
  882.       CLASS_ClassDFTable
  883.          (DPFUNC *) Pointer to the class dispatcher's function lookup table
  884.          array.  This array lists all methods that the class supports
  885.          and function pointers to each of the methods.  (same format as
  886.          CLASS_DFTAble)
  887.  
  888.  
  889. RESULT
  890.  
  891.    A pointer to a valid Class structure, or NULL if the class could not be
  892.    created.
  893.  
  894. NOTES
  895.  
  896.    The global data pointer that is stored in register A4 is restored upon
  897.    exiting this function; thus, you need not use __saveds in your method
  898.    dispatcher functions.
  899.  
  900. BUGS
  901.  
  902.    None known.
  903.  
  904. SEE ALSO
  905.  
  906.    libraries/bgui.h, bgui.library/FreeClass()
  907.  
  908.  
  909.  
  910.  
  911.  
  912. bgui.library/BGUI_NewObjectA
  913.  
  914. NAME
  915.  
  916.    BGUI_NewObjectA -- Create an object of a specific class.
  917.    BGUI_NewObject -- Varargs version.
  918.  
  919. SYNOPSIS
  920.  
  921.    object = BGUI_NewObjectA( classID, tags )
  922.    D0                        D0       A0
  923.  
  924.    Object *BGUI_NewObjectA( ULONG, struct TagItem * )
  925.  
  926.    object = BGUI_NewObject( classID, tag1, ... )
  927.  
  928.    Object *BGUI_NewObject( ULONG, Tag, ... )
  929.  
  930. FUNCTION
  931.  
  932.    This routine is a replacement routine for Intuition's NewObjectA() call.
  933.    It is an easy way to obtain an object from any of the BGUI classes. You
  934.    pass it a classID and some create time attributes and the routine will
  935.    return you a pointer to the created object.
  936.  
  937. INPUTS
  938.  
  939.    classID  -  The numeric ID of the class.
  940.    tags     -  A set of create-time attributes which will be passed to the
  941.                class from which the object is created.
  942.  
  943. RESULT
  944.  
  945.    A pointer to the created object or NULL if an error occured.
  946.  
  947. BUGS
  948.  
  949.    None known.
  950.  
  951. SEE ALSO
  952.  
  953.    intuition.library/NewObjectA(), libraries/bgui.h
  954.  
  955. bgui.library/BGUI_PackStructureTags
  956.  
  957. NAME
  958.  
  959.    BGUI_PackStructureTags -- Pack a structure with values from a TagList.
  960.  
  961.    ** V41.8 **
  962.  
  963. SYNOPSIS
  964.  
  965.    num = BGUI_PackStructureTags (pack, pTable, taglist)
  966.    D0                            A0    A1      A2
  967.  
  968.    ULONG BGUI_PackStructureTags( APTR, ULONG *, struct TagItem *)
  969.  
  970. FUNCTION
  971.  
  972.    For each pTable entry, a FindTagItem() will be done and if the matching
  973.    tag is found in the taglist, the data will be packed into the given
  974.    structure based on the packtable definition.
  975.  
  976. INPUTS
  977.  
  978.    pack     -  A pointer to the data space to be packed into.
  979.  
  980.    pTable   -  A pointer to the packing information table. See utility/pack.h
  981.                for definition and macros.
  982.  
  983.    taglist  -  A pointer to the TagList to pack from.
  984.  
  985. RESULT
  986.  
  987.    The number of tags packed.
  988.  
  989. NOTES
  990.  
  991.    if the user is using V39 or later of the OS,
  992.    utility.library/PackStructureTags() will be used. Otherwise, internal
  993.    bgui.library functions will be used.
  994.  
  995. BUGS
  996.  
  997.    None known.
  998.  
  999. SEE ALSO
  1000.  
  1001.    libraries/bgui.h, bgui.library/BGUI_UnpackStructureTags(), utility/pack.h,
  1002.    utility.library/PackStructureTags()
  1003.  
  1004.  
  1005.  
  1006. bgui.library/BGUI_PostRender
  1007.  
  1008. NAME
  1009.  
  1010.    BGUI_PostRender -- Perform operations on a class after rendering.
  1011.  
  1012.    ** V41.6 **
  1013.  
  1014. SYNOPSIS
  1015.  
  1016.    BGUI_PostRender( class, object, gp_render)
  1017.                     A0      A2     A1
  1018.  
  1019.    void BGUI_PostRender( struct Class *, struct Object *,
  1020.                          struct gpRender * )
  1021.  
  1022. FUNCTION
  1023.  
  1024.    This function is only for class implementors that subclass from
  1025.    baseclass and implement the GM_RENDER method.
  1026.  
  1027.    It is called with the same arguments that GM_RENDER was called with, and
  1028.    should be called you exit the rendering function. Do not call it if the
  1029.    superclass method failed. Call it in all other cases.
  1030.  
  1031. INPUTS
  1032.  
  1033.    class -  A pointer to a Class structure that the object belongs to.
  1034.  
  1035.    obj   -  A pointer to the object.
  1036.  
  1037.    gpr   -  A pointer to a gpRender structure with the fields set up as
  1038.             appropriate:
  1039.  
  1040.                ULONG MethodID
  1041.                   Set to GM_RENDER
  1042.  
  1043.                struct GadgetInfo *gpr_GInfo
  1044.                   Set to point to the object's GadgetInfo structure.
  1045.  
  1046.                struct RastPort *gpr_RPort
  1047.                   Set to point to the object's RastPort
  1048.  
  1049.                LONG gpr_Redraw
  1050.                   Redraw method one of the following three values:
  1051.  
  1052.                      GREDRAW_REDRAW
  1053.                         Redraw the entire gadget
  1054.  
  1055.                      GREDRAW_UPDATE
  1056.                         The object's imagry has changed, possibly due to the
  1057.                         user manipulating the object. Only the part of the
  1058.                         imagry that was affected will be redrawn (e.g., a
  1059.                         slider object)
  1060.  
  1061.                      GREDRAW_TOGGLE
  1062.                         If the object supports it, toggle between the
  1063.                         selected and unselected state.
  1064.  
  1065. RESULT
  1066.  
  1067.    No returned result.  If successful, the object will re redrawn as needed.
  1068.  
  1069. NOTES
  1070.  
  1071.    This function was implemented in V41.6 to support recursive clipping and
  1072.    buffering with virtual groups in mind.
  1073.  
  1074.    Do not use objects in virtual groups if their classes do not call this
  1075.    function. If you must use an old pre-compiled class, you'll have to use
  1076.    it with the externalclass.
  1077.  
  1078. BUGS
  1079.  
  1080.    None known.
  1081.  
  1082. SEE ALSO
  1083.  
  1084.    libraries/bgui.h, intuition/gadgetclass.h
  1085.  
  1086.  
  1087.  
  1088. bgui.library/BGUI_RequestA
  1089.  
  1090. NAME
  1091.  
  1092.    BGUI_RequestA -- Put up a text requester.
  1093.    BGUI_Request -- Varargs version.
  1094.  
  1095. SYNOPSIS
  1096.  
  1097.    gadid = BGUI_RequestA( win, req, args )
  1098.    D0                     A0   A1   A2
  1099.  
  1100.    ULONG BGUI_RequestA( struct Window *, struct bguiRequest *, ULONG * )
  1101.  
  1102.    gadid = BGUI_Request( win, req, arg1, ... )
  1103.  
  1104.    ULONG BGUI_Request( struct Window *, struct bguiRequest *, ULONG, ... )
  1105.  
  1106. FUNCTION
  1107.  
  1108.    To put up a requester. It is typically the same as Intuition's
  1109.    EasyRequestArgs() only this routine allows you to put InfoClass style
  1110.    command sequences in the body text and keyboard shortcuts for the
  1111.    gadgets.
  1112.  
  1113. INPUTS
  1114.  
  1115.    win   -  A pointer to the window on which the requester will open. This
  1116.             may be NULL.
  1117.  
  1118.    req   -  A pointer to an initialized bguiRequest structure. This
  1119.             structure is similar to Intuition's EasyStruct structure.
  1120.             It is used to control the general look of the requester. The
  1121.             structure is initialized with the following data:
  1122.  
  1123.             br_Flags -  This field can contain any of the following
  1124.                         flags:
  1125.  
  1126.                         BREQF_CENTERWINDOW
  1127.  
  1128.                            This will center the requester over the
  1129.                            window 'win' if a valid pointer to a
  1130.                            window is passed.
  1131.  
  1132.                         BREQF_LOCKWINDOW
  1133.  
  1134.                            This will disable the window on which
  1135.                            the requester appears from receiving any
  1136.                            IDCMP messages. A busy pointer is also
  1137.                            set on that window. NOTE: 'win' must
  1138.                            point to a window for this to work.
  1139.  
  1140.                         BREQF_NO_PATTERN
  1141.  
  1142.                            This will suppress the backfill pattern.
  1143.  
  1144.                         BREQF_XEN_BUTTONS
  1145.  
  1146.                            When set this flag will make the buttons
  1147.                            framing appear as XEN style framing.
  1148.  
  1149.                         BREQF_AUTO_ASPECT
  1150.  
  1151.                            When set all the requester will make
  1152.                            some aspect ratio dependant changes to
  1153.                            the GUI like thin/thick frames etc.
  1154.  
  1155.                         BREQF_FAST_KEYS
  1156.  
  1157.                            This flag tells BGUI to use the Return
  1158.                            and Esc key as default positive/negative
  1159.                            response to the requester. Please note
  1160.                            that no visual confirmation is given
  1161.                            at this time when the key is pressed.
  1162.  
  1163.             br_Title -  A pointer to the title of the requester.  If
  1164.                         this is NULL the title of the window is used
  1165.                         if one is present. As a final default, "BGUI
  1166.                         Request" or its localized equivalent is
  1167.                         used.
  1168.  
  1169.      br_GadgetFormat -  A pointer to the gadget label string. The
  1170.                         gadget labels are seperated by a  '|'
  1171.                         character. I.E "OK|Cancel" will give you an
  1172.                         "OK" and a "Cancel" gadget.
  1173.  
  1174.                         When you precede the gadget label with a '*'
  1175.                         the label of the gadget in question will be
  1176.                         rendered as bold text, and  also will
  1177.                         automatically be the default response of the
  1178.                         Return key when the BREQF_FAST_KEYS flag is
  1179.                         set (see above).
  1180.  
  1181.        br_TextFormat -  A printf-style formatting string which may
  1182.                         also contain InfoClass style command
  1183.                         sequences.
  1184.  
  1185.            br_ReqPos -  The position at which the requester will
  1186.                         be opened.  There are three possibilities:
  1187.  
  1188.                         POS_CENTERSCREEN
  1189.  
  1190.                            Center requester on the window's (if any)
  1191.                            screen.
  1192.  
  1193.                         POS_CENTERMOUSE
  1194.  
  1195.                            Center requester under mouse pointer, if
  1196.                            possible.
  1197.  
  1198.                         POS_TOPLEFT
  1199.  
  1200.                            Open requester in the top left corner of
  1201.                            the window's screen (similar to how Intuition's
  1202.                            EasyRequest does it).
  1203.  
  1204.                         NOTE: The BREQF_CENTERWINDOW  flag  will override
  1205.                         this setting.
  1206.  
  1207.        br_Underscore -  With this field you can set the character
  1208.                         which preceedes the character to underline.
  1209.                         The underlined character will automatically become
  1210.                         the key which activates the gadget.
  1211.  
  1212.         br_Reserved0 -  This field is for future expansion and
  1213.                         _must_ be set to zero.
  1214.  
  1215.            br_Screen -  Here you can optionally specify the Screen
  1216.                         on which the requester must appear. By
  1217.                         default the given window's Screen is used if a
  1218.                         valid Window pointer is given. If no Window
  1219.                         is given then this Screen is used. If this
  1220.                         field is NULL the default Public Screen is
  1221.                         used.
  1222.  
  1223.         br_Reserved1 -  These fields are for future expansion and
  1224.                         _must_ be zero'd.
  1225.  
  1226.    args  -  A pointer to an array of arguments for the C-style formatting
  1227.             codes.
  1228.  
  1229. RESULT
  1230.  
  1231.    1, 2, 3, 4 ....., 0.
  1232.  
  1233.    You will be returned a value ranging from 0 to the count of gadgets minus
  1234.    one.   NOTE: The right most gadget will always return 0.
  1235.  
  1236. SEE ALSO
  1237.  
  1238.    intuition.library/EasyRequestArgs(), intuition/intuition.h,
  1239.    libraries/bgui.h, infoclass.doc
  1240.  
  1241. bgui.library/BGUI_UnlockWindow
  1242.  
  1243. NAME
  1244.  
  1245.    BGUI_UnlockWindow -- Enable a window that was previously disabled.
  1246.  
  1247. SYNOPSIS
  1248.  
  1249.    BGUI_UnlockWindow( lock )
  1250.                       A0
  1251.  
  1252.    VOID BGUI_UnlockWindow( APTR )
  1253.  
  1254. FUNCTION
  1255.  
  1256.    To enable a window to receive IDCMP messages on its message port. This
  1257.    routine must be used to 'unlock' windows locked with BGUI_LockWindow().
  1258.  
  1259. INPUTS
  1260.  
  1261.    lock  -  A pointer to the data returned by BGUI_LockWindow(). This may
  1262.             be NULL.
  1263.  
  1264. RESULT
  1265.  
  1266.    The window will be unlocked.
  1267.  
  1268. BUGS
  1269.  
  1270.    None know.
  1271.  
  1272. SEE ALSO
  1273.  
  1274.    bgui.library/BGUI_LockWindow()
  1275.  
  1276. bgui.library/BGUI_UnpackStructureTags
  1277.  
  1278. NAME
  1279.  
  1280.    BGUI_UnpackStructureTags -- unpack a structure into values in a TagList.
  1281.  
  1282.    ** V41.8 **
  1283.  
  1284. SYNOPSIS
  1285.  
  1286.    num = BGUI_UnpackStructureTags (pack, pTable, taglist)
  1287.    D0                              A0    A1      A2
  1288.  
  1289.    ULONG BGUI_UnpackStructureTags( APTR, ULONG *, struct TagItem *)
  1290.  
  1291. FUNCTION
  1292.  
  1293.    For each pTable entry, a FindTagItem() will be done and if the matching
  1294.    tag is found in the taglist, the data in the structure will be placed into
  1295.    the memory pointed at by the tag's ti_Data. ti_Data MUST be a LONGWORD.
  1296.  
  1297. INPUTS
  1298.  
  1299.    pack     -  A pointer to the data space to be unpacked.
  1300.  
  1301.    pTable   -  A pointer to the packing information table. See utility/pack.h
  1302.                for definition and macros.
  1303.  
  1304.    taglist  -  A pointer to the TagList to unpack into.
  1305.  
  1306. RESULT
  1307.  
  1308.    The number of tags unpacked.
  1309.  
  1310. NOTES
  1311.  
  1312.    if the user is using V39 or later of the OS,
  1313.    utility.library/UnpackStructureTags() will be used. Otherwise, internal
  1314.    bgui.library functions will be used.
  1315.  
  1316. BUGS
  1317.  
  1318.    None known.
  1319.  
  1320. SEE ALSO
  1321.  
  1322.    libraries/bgui.h, bgui.library/BGUI_PackStructureTags(), utility/pack.h,
  1323.    utility.library/UnpackStructureTags()
  1324.  
  1325.  
  1326.  
  1327.